3D Graphics Programming with QuickDraw 3D 1.5.4

Rendering an Image

Once you have created and configured a view, you can use it to render an image of a model. To do so, you need to enter into the rendering state by calling the Q3View_StartRendering function. Then you specify the model to be drawn and call Q3View_EndRendering . Because the renderer might not have had sufficient memory to complete the rendering when you call Q3View_EndRendering , you might need to respecify the model, to give the renderer another pass at the model's data. As a result, you almost always call Q3View_StartRendering and Q3View_EndRendering in a rendering loop, shown in outline in Listing 1 .

Listing 1 Rendering a model



 
Q3View_StartRendering(myView);

do {

    /*submit the model here*/

} while (Q3View_EndRendering(myView) == 

                                            kQ3ViewStatusRetraverse);

The Q3View_EndRendering function returns a view status value that indicates the status of the rendering process. If Q3View_EndRendering returns the value kQ3ViewStatusRetraverse , you should reenter your rendering loop. If Q3View_EndRendering returns kQ3ViewStatusDone , kQ3ViewStatusError , or kQ3ViewStatusCancelled , you should exit the loop.

As you know, QuickDraw 3D supports immediate mode, retained mode, and mixed mode rendering. You use a rendering loop for all these rendering modes, but they differ in how you create and draw the objects in a model. To use retained mode rendering, you let QuickDraw 3D allocate memory to hold the data associated with a particular object or group of objects. For example, to render a box in retained mode, you must first create the box by calling the Q3Box_New function. Then you draw the box by calling the Q3Geometry_Submit function, as illustrated in Listing 2 .

Listing 2 Creating and rendering a retained object



 
TQ3BoxData                  myBoxData;

TQ3GeometryObject           myBox;



Q3Point3D_Set(&myBoxData.origin, 1.0, 1.0, 1.0);

Q3Vector3D_Set(&myBoxData.orientation, 0, 2.0, 0);

Q3Vector3D_Set(&myBoxData.minorAxis, 2.0, 0, 0);

Q3Vector3D_Set(&myBoxData.majorAxis, 0, 0, 2.0);

myBox = Q3Box_New(&myBoxData);



Q3View_StartRendering(myView);

do {

    Q3Geometry_Submit(myBox, myView);

} while (Q3View_EndRendering(myView) == 

                                            kQ3ViewStatusRetraverse);

In general, you use retained mode rendering when much of the model remains unchanged from frame to frame. For retained mode rendering, you can use the following routines inside a rendering loop:



 
Q3Style_Submit

Q3Geometry_Submit

Q3Transform_Submit

Q3Group_Submit

To use immediate mode rendering, you allocate memory for an object yourself and draw the object using an immediate mode drawing routine, as illustrated in Listing 3 .

Listing 3 Creating and rendering an immediate object



 
TQ3BoxData                      myBoxData;



Q3Point3D_Set(&myBoxData.origin, 1.0, 1.0, 1.0);

Q3Vector3D_Set(&myBoxData.orientation, 0, 2.0, 0);

Q3Vector3D_Set(&myBoxData.minorAxis, 2.0, 0, 0);

Q3Vector3D_Set(&myBoxData.majorAxis, 0, 0, 2.0);



 
Q3View_StartRendering(myView);

do {

    Q3Box_Submit(myBoxData, myView);

} while (Q3View_EndRendering(myView) == 

                                            kQ3ViewStatusRetraverse);

In general, you use immediate mode when your application does not need to retain the geometric data for subsequent use.